3 ms·
I’m going to relate an experience rather than answer your question. I don’t think the question is in its best form because it can be time consuming to write pro
by tyleo 7y ago
I’m going to relate an experience rather than answer your question. I don’t think the question is in its best form because it can be time consuming to write proper documentation. The existence of the “fairy godmother” takes time out of the equation which is an important variable.
I used to work at Microsoft on a team with poor documentation. By my reckoning developers writing code would have preferred better documentation while developer managers couldn’t justify the time to write it. Both preferences were sensible.
From the implementer perspective you could get caught up on a problem for several hours before having a conversation with another developer who could unblock you instantly. If the content of that conversation had existed in some document it could have been searched and several hours could have been saved.
From the managers perspective, product requirements and features changed so rapidly that a few days spent writing documentation could easily create a document that no one would use. Indeed, this was the case in a few experiments.
I lead a team for awhile and we hit the first problem a lot. However, I noticed that most of the conversations which unblocked my team had happened over email (I was CC’d). The tone of emails did not make for perfect documentation but they were helping my team so they were better than nothing. I decided to start taking some of the emails and pasting them into a OneNote document. After a few months the result was a large collection of imperfect documentation created very economically.
The OneNote document was wildly successful:
* Because the notes were from emails which had at least unblocked one member of my team, they had proven value.
* Because developers were already writing emails there was low cost to pasting them in OneNote.
* Developers could also correct the OneNotes and everyone would get the changes unlike an email thread which was only accessible to people on the to and cc field.
I also believe that the imperfections and limited editing features of email made it easier for people to write these documents: they didn’t feel like the documents needed to be well-formatted or perfectly written, if someone had something to say they had unlimited license to paste it in the document.
So thats been my experience and I will bet on it again in the future. The only caveat is that I worked on games which is the cause of the rapidly changing requirements. “Unfun” features could entirely be cut and we essentially rebuilt the product every few years to release a new game obsoleting much of the documentation. This sort of thing may not work for a public facing API for example.
- jnxx 7y ago> The existence of the “fairy godmother” takes time out of the equation which is an important variable. I know that good documentation takes time. What you write about OneNote is interesting. The only caveat is that using Microsoft Windows would be extremely unproductive in this environment (it is embedded software which needs to run on a Linux platform, so using Windows for documentation creates a lot of additional friction). I think this basically has the features of a Wiki in which you could insert emails and other help information, and whose organization can be ordered and evolved over time. Do you have any experience with [Zim Wiki](https://zim-wiki.org/ https://zim-wiki.org/) (a Desktop Wiki software) or Docuwiki (which is tailored especially for documentation) ? I've used the former quite successful for personal information management (it is free software, with free as in "free speech", and it even runs under Windows). What I like especially about it is that it can be integrated really easy into version control with git, or use the existing git version control of the corresponding code. At some points in my past, I've also used [Dokuwiki](https://www.dokuwiki.org/dokuwiki https://www.dokuwiki.org/dokuwiki) very, very successfully as member of a group. For other environments, wikis do not seem to work so well - I am still struggling to understand what makes the difference.
- tonyarkles 7y agoI am a Linux guy through and through, but I have an old Surface 3 that I take to meetings and coffee shops. The web version of OneNote (via Office 365) works awesome for reading OneNote notebooks and for writing typed text. From the Surface I'll usually use the pen and then type up a summary later. Search on my messy handwriting usually works pretty well too.
- jnxx 7y agoWhat I remember, don't have the surface notebooks serious problems with both built quality and Linux power saving? Personally, I've zoomed in on Thinkpads, old business models. They are sometimes a bit bulky, but rugged. They don't break and can be upgraded and repaired well. The old ones have really good keyboards which is important for me as a console user. And they have usually out-of-the box good driver support. And that's something I am expecting today. 20 Years ago, I tolerated a lot of driver problems, as I was a poor student and Linux driver support was often patchy. Today, I expect that it just works. And last, given Microsoft's history with Nokia, Maemo, and the N9, I would not expect any reliable Linux hardware support from Microsoft (Fool me twice, shame on me).