Daniele Procida - How documentation works, and how to make it work for your project - PyCon 2017

Development
,
1

@jcfr mentioned this talk to me, and I thought it is a good investment of 30 min time to at least listen to it.

1 Like
2

Thank you, it was an interesting talk.

I haven’t thought about strictly distinguishing between “tutorial” (training where the user gets a sample problem and a solution) and “how-to” (training where the user brings his own problem and gets a solution). It’s probably a good idea.

I’m not sure where or how “discussion” type of information could be documented for Slicer. Does the forum and/or wiki already provides this information in a good format?

3

I was thinking that things like project week projects all the way up to journal publications serve as the “discussion” type of information because they address starting with an unsolved problem and then evaluating and testing the possible solutions.

I liked the four-quadrant breakdown and maybe we can reorganize our content along those lines.

4

For reference, here is the four-quadrant illustration.

Screenshot from 2017-07-27 15-31-17
Screenshot from 2017-07-27 15-31-171074Ă—617 242 KB

5

I am not sure myself. I thought that in case of Slicer, things like overview of the pros and cons of different formats, coordinate systems explanation, historical perspectives - these belong to a discussion section.

It is interesting that if you look at the Django documentation that was used as a model in that talk, they do not have Discussions, but have Topic guides. Maybe that replaced Discussions (or is waiting to be replaced by Discussions!).