You should adapt the format you use to what you are trying to convey. Standard formats are for machines. Brains are contextual. Be flexible. Think about what it will look like for the reader.
Show this thread
Software documentation is a communication medium. Many SWEs apparently perceive it as a kind of configuration object, something that needs to check a number of technical checkboxes. No, that's not it. Your audience is other human beings.
-
-
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
-
-
Software engineers should not write documentation. They are so bad at it.
-
Then they need to practice
End of conversation
New conversation -
-
-
What are your thoughts on the documentation for Tensorflow?
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
-
-
Tech interviews don't screen you for writing ability but if they did and if the impact of documentation is properly measured (e.g: monthly readers) then you can start getting to a culture where impactful documentation is as celebrated as impactful code.
-
I am sick and tired of receiving “documentation” which uses 20 pages of randomly formatted content to explain absolutely nothing.
End of conversation
New conversation -
-
-
Thank you for this. It’s sad that documentation is so often treated as an afterthought. It doesn’t matter what software can do if it’s functionality is obfuscated by poorly composed communication.
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
-
-
The deeper tensorflow documents used to be like something from another language. I regularly would send a text to a friend saying "man f*!k tensorflow" they have really come a long way.
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
-
-
A Tweet which should be read by the developers of a certain DL-framework based on PyTorch and claiming tremendous ease of use and power while having essentially no documentation at all…
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
-
-
What do you think is the best way/format to document data format collaboratively (format and meaning of data received, transformation occurring and output format) ?
Thanks. Twitter will use this to make your timeline better. UndoUndo
-
Loading seems to be taking a while.
Twitter may be over capacity or experiencing a momentary hiccup. Try again or visit Twitter Status for more information.