111–120 of 220 posts
Also be realistic about how the documentation will be used. I found this paper and its references useful:
1. Working in pairs or teams. Avoid solo people working on projects. 2. Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. 3. A good code & commit search engine. Ability to search code reliably obviates the need for a lot of documentation. 4. Weekly knowledge sharing sessions with the whole team. Both presenters and question askers need to be rewarded to keep…
Re: easy search. Slapdash can handle search in all your work wikis/docs at once and is very fast. It can search github/gitlab too. I am part of the team there.
Every commit should combine: - The code change itself - Tests that demonstrate that the change works as expected - Updated documentation relevant to that change (documentation should live in the same repo as the code to support this) - A link to the ticket/issue that discusses the change If you use a code review system such as GitHub pull requests or Phabricator you can enforce this kind of commit culturally - in you…
I'm more inclined than most of my team to do cleanup commits, but even I sometimes avoid them just for the extra cost of the regular review process.
I think a better approach is to have a culture that encourages making context dependent judgement calls, which is also what I try to do.
If it's something trivial like fixing a typo, I ask that this is made clear in the title, so investigators of an issue know that this CL is unlikely to be relevant.
If it's a minor change in behaviour, I ask for a commit message, and/or a comment in code, with a motivation of why it's needed.
If it's a bigger change in behaviour I want an issue linked to it, to make tracking easier in case there's followups needed or there's some regression due to this.
All this is of course based, not on some platonic ideal of what makes for good documentation, but rather on real experience of tracking down issues and adding features.
I know how annoying it can be to track down the commit of some functionality that looks really odd, only to find an empty message without even a reference to the issue that was being solved. But I also don't have this problem with commits that are clearly labeled "Fixed typo in X", those I can simply ignore.
Earlier quoted context omitted.
Ideally, the automation is available and can be read through to divine the steps it is taking to perform the task. As for the thought process, pray that the author left behind hints whether that be in the form of comments in code, descriptive commit messages, etc. Otherwise it gets a bit more tricky.
Comments and commit messages are documentation and knowledge capture, but done in a way that's really hard to read through and requires technical knowledge and repo permissions to even access. If your team includes people who aren't developers and you need to review a process it's very useful to have that knowledge in a more readable format.
In practice... Well, the initial question was about good practices so perhaps we shouldn't lift the lid on bitter experience.
https://zwischenzugs.com/2017/04/04/things-i-learned-managin...
Specifically here, the importance of:
- allocating budget to the maintenance of knowledge
- rotating the responsibility for maintenance around the group
- co-locating the knowledge store with the day-to-day tooling, even if that doesn't conform to document management ideals
1. Working in pairs or teams. Avoid solo people working on projects. 2. Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. 3. A good code & commit search engine. Ability to search code reliably obviates the need for a lot of documentation. 4. Weekly knowledge sharing sessions with the whole team. Both presenters and question askers need to be rewarded to keep…
> Common, easily searchable place to put all documentation at. Good search capability is critical. Wiki is ok. I have mixed feelings around documentation because I can often read the code faster than the docs, and docs are often incomplete, inaccurate, and out-of-date. Docs for truly long-lived things are nice, though. As for good search, that's easier said than done. The heuristics Google used for search don't work…
- unit tests show how well the developer understood the requirements at the time they wrote the code - git commit history shows who and when something changed (probably assuming history not rewritten :) ) - git history can be more informative, if and it is a big if, the developers write enough information and not just “changed code” type comments - in-line comments are for “why” - explaining things that look odd or go against standards or best practices, or “I’m doing this now like this, when x is available use that” - notes to help you and others - wiki is for higher level “why” to help people understand the code, where there is a lot of complexity I really like the idea of a “book of the xx” like the book of the runtime here: https://www.hanselman.com/blog/TheBookOfTheRuntimeTheInterna...
However, to make the institutional knowledge useful, it must be easy to find. Thus, I think the second most important thing for capturing institutional knowledge is to have a small number of easily searchable places where documentation lives. Markdown files in the source are convenient place for documenting particular projects or code, but more general-purpose knowledge should be in a wiki or any other document store that is centrally searchable and update-able. An example of such general purpose knowledge is "how-to knowledge": How do I request the appropriate privileges to integrate my service with Service X? How do I make and deploy a staging build? How do I set up a new service?
Another sort of general-purpose knowledge that should have a single home is knowledge around context for past decisions that were made for good, but not obvious reasons. My team maintains a document called a Decision Log, where we record the context around and reasons for every decision that required more than roughly 10 minutes of thought. Longer decisions have their own docs, but they are linked from the central Decision Log.
Earlier quoted context omitted.
This is what I do. And if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. I also write comments first when writing complex code and then fill in the code in between. More than once this helped more than any documentation could, because people do not read documentation if they can avoid it, and avoid it they'll try.
I’m also a big markdown-in-source advocate. However it’s major shortcoming is that it’s not accessible enough for non-technical teams to maintain.
Markdown is fine until you realize you would like to have figures, images and tables.
I don't want to spend my time over trite details of a text based markup when I could spend it actually productively.
At that point it's way over easier to use a text processing document of choice (word or open office). I say this as a enthusiast of text based markups over decades from Latex to Markdown.
Store readme markdown files in the sourcerepo along with the code itself. Make sure during review that changes to code are reflected in the markdown. Doesn't need to be exhaustive docs - usually just a high- to medium-level explanation of what why and how goes a long way. Controversial/surprising/confusing choices should be documented in several places - e.g. in the readme, in a bug/ticket, in the check-in comments a…
This is what I do. And if the Markdown file is not near the code in question, it's a 100% guarantee you've wasted time writing it because nobody is going to read it. I also write comments first when writing complex code and then fill in the code in between. More than once this helped more than any documentation could, because people do not read documentation if they can avoid it, and avoid it they'll try.
This ignores hyperlinks. Why not use in-code comments for explaining nuts-and-bolts matters (for example, to explain strange-looking platform-sensitive code using #ifdef), and use links to wiki pages for descriptions of high-level design decisions?