![]() ![]() ![]() There remains the practical limit that Markdown also inherits that HTML only has 6 levels. That's a total of 42 suggested options for heading levels, and not even the "limit". Then there's dozens of possible symbols ("printing nonalphanumeric 7-bit ASCII character"), and the documentation/primer narrows that to a suggested interesting looking 14 options of ASCII symbols. In rST there are three choices of "line-style": underline, overline, both under and overline. ![]() I still use md for READMEs and gists and whatnot, I guess my point is, different tools for different jobs, if you have to pull weeds in your garden use a spade, if you have to do it for a field use a machine, or something. I dunno, I've done both and I just have a much better time with RST once the project size gets past a single doc. But then when you start needing features for big documents like cross references, highlighted syntax blocks, images, ToC, figures, etc it RST has all that built in and you don't have to reach for some markdown superset (although I guess you could argue Sphinx is that for RST). Like the basic features are mostly identical. Actually in a way rst is better for links since the common thing in markdown is to reference links like this, in RST with _ instead that actually works and this becomes a hyperlink. Inline hyperlinks are about the only thing that aren't visually nice like they are in markdown, (text) vs _ or w/e it is (I use sphinx refs so I don't recall exactly). `code` vs ``code``, or just an indented block (in rst just add :: before the block start), emph is still emph, you can still use = and - for headers, bullet lists are the same as markdown, and so on. I don't really understand this, the same markup you get from markdown has about the same surface area in terms of syntax in rst. I've had the markdown vs rst discussion with a few people a few times and the pro-markdown people always cite this, saying rst is much harder to use or the core syntax is awkward in comparison. Meanwhile I'd just like some documentation at all. It's been a great help - sometimes the original implementors can't remember why something was done the way it was done - especially when asked three or more years later.Īdmonishing people to write documentation in Markdown would be a nice problem for me to have. On the teams I've been working with I've gotten them to capture these decisions. What decisions were explicitly made and why were they made? All too often when looking at code I can certainly understand what was done, but it's not at all immediately clear as to why. Software embodies several architectural and design decisions. Source code answers the how and what but it doesn't provide any answer to the most important question of all - why? Even documentation written in Markdown is better than the nothing that all-too-often gets created.Ī lot of programmers argue the code is the best documentation. Meanwhile programmers are like: Please write documentation! Please. It might be very useful for understanding the system. Is it an emergency runbook? Well then either that info is important enough to walk through it periodically, or you should be honest with yourself that what that doc really says is, "This was the suggested runbook we came up with after a post-mortem 2 years ago. If that is the case, then why should they spend time and attention to keep it up-to-date? If a page is rarely-read by others, then the team which owns it is not pointing people to it or using it for training. Marks the page as stale within a week of non-response.Ģ) Mark the page as stale if the text isn't updated at least every 3 months.ģ) Mark the page as stale if it doesn't get at least N page-views in 3 months. Ideally, there would be a tool which attaches to every "Maintained" page and does 3 things.ġ) Let the reader mark it as possibly stale or ask a question, then messages the page owners about that. Every maintained page is owned by a team of 2-10 people and the channel to contact them is visible on the page. Why? To keep small the number of docs which are "Maintained". Reports become historical records after 1-3 months. When you write docs, be very clear whether you are writing a new report or something you intend to maintain. Record: "This is a historical record of our intended system design, produced on. News: "This represents our current thinking as of 2" Message #slack-channel with any questions." Maintained: "We are maintain this and aim to keep up to date. Here is my proposal for any sort of docs that don't live right alongside the code. ![]()
0 Comments
Leave a Reply. |
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |