Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Possible Blog Article: PSIP for impoving documentation #1950

Open
fryeguy52 opened this issue Dec 21, 2023 · 2 comments
Open

Possible Blog Article: PSIP for impoving documentation #1950

fryeguy52 opened this issue Dec 21, 2023 · 2 comments
Labels
content: blog For blog content external contribution Issue or PR from outside of the BSSw editorial team

Comments

@fryeguy52
Copy link

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

@fryeguy52 fryeguy52 added the content: blog For blog content label Dec 21, 2023
@github-actions github-actions bot added the external contribution Issue or PR from outside of the BSSw editorial team label Dec 21, 2023
@markcmiller86
Copy link
Member

@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
Copy link
Member

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
content: blog For blog content external contribution Issue or PR from outside of the BSSw editorial team
Projects
Status: In progress
Development

No branches or pull requests

3 participants