documentation
Fri, Jun 29, 2018 | applications, documentation, personal, reviews
This is a quick review of Bear Writer, a popular note-taking application that I tried out a few weeks ago. A much larger and more detailed post about my overall quest for a note-taking solution (I have very picky, perhaps contradictory requirements) is forthcoming! The good Bear is a beautiful set of applications. Attractive without being ostentatious or getting in the way, pretty quick/slick to use, desktop and mobile apps clearly resemble each other, etc. It uses the relatively common “show raw Markdown text, styled accordingly” (e.g. text within asterisks still shows the asterisks, but is also bolded) approach which works quite well most of the time – with most exceptions being endemic to the approach itself and not Bear’s implementation. Checklist support is better than in some similar apps, including good keyboard shortcuts, an attractive strike-thru of checked list items, and optional ‘folding’/hiding; though see the next section for a bunch of pitfalls with this feature area. Organization is effected through tags (including nesting via forward-slashes in the tag names) and it feels simple yet powerful. Attention to detail is clear; for example, creating a new note while filtering by a given tag automatically tags the new note with that tag.



Sun, Sep 29, 2013 | documentation, maintainership, sphinx

Most open source projects store documentation in the source repo itself. This is easy to do, allows the doc builder to reference in-code documentation (like Python docstrings), makes contributions from others simpler, etc.

However, it doesn’t always play nice with “meta” information such as how to contribute, project roadmap, and so forth.