Possible Blog Article: PSIP for impoving documentation

[fryeguy52]

Efficient and effective workflows for software documentation are not obvious. Choices concerning when and how to invest time in project documentation are weighed against time invested in development. This can be especially true when a project is new and changing rapidly. It is non trivial to decide when to invest time into documentation of a feature when that feature is still under development. This article would discuss relevant experience in a young fast-moving single developer project using PSIP as a means to enact positive change on the documentation process and policy. The PSIP focused on integrating note book style documentation into the workflow with a small investment while doing the work to lower the cost of creating more complete documentation later. We considered if the documentation is explaining why decisions were made, or if it is related to a common developer or user workflow. We also considered different attributes of documentation such as the intended audience and value for reproducibility. Based on these factors we determined which kinds of documentation warrant the most effort and refinement, and which are sufficient as less formal notes. We would like to discuss our experience using PSIP including where it helped, and where PSIP had difficulty gaining traction.

@jwillenbring @elaineraybourn

[markcmiller86]

@fryeguy52 thanks for reaching out. This topic sounds very interesting and relevant for bssw.io. We would be happy to review a proposed article on this topic. Please refer to these guidelines to help inform your content development.

[bernhold]

Hi @fryeguy52, I wondered whether you've been able to make any progress on this article? Maybe we should set a due date for a draft so that we both have a target to work towards? What would work for you? Thanks