Guidelines for Design Docs
- Anne Urban
Break your project into manageable pieces
You may find that you need to break a large contribution into smaller, workable pieces. The same guidelines apply to each separate piece.
Do you need a design doc?
For simple changes, you can just open a pull request and describe what you're doing in the PR. For more complex changes, you can create a design doc. If you are not sure, ask on the developer forum.
Announce and discuss your design
If you do need a design doc, create one in the project documentation space, and announce it on the developer forum. In your announcement, put a link to the design doc, with a brief description. The initial draft of your design only needs a title and an overview.
When you start your topic, use a summary of the feature or bug for your topic title, for example, "Server Periodic Hook". In the forum discussion, add a pointer to your design page. Use the developer forum for all your design discussions.
Make your design useful and readable
Be kind to your readers: try to answer questions in your design doc so that other developers, admins, job submitters, testers, and publications people can get the info they need. Be concise, include diagrams and examples, and keep the design doc up to date. Put a concise, descriptive, unique title at the top. If the design is associated with an issue ID, include it. After you've started the forum discussion, it's helpful to include a link in the design doc that goes to the discussion on the developer forum. Later, when you create your pull request, you can link to it as well.
Describe the change you're making. Explain how it makes the world a better place. Make sure that non-coders can understand what you're saying. Explain how it's used, and by whom.
If you're adding a new interface, explain how to use it (and when not to use it). If you're adding a new PBS element such as an attribute or parameter, include the same kinds of information about it that are in the definitions in the PBS Pro Reference Guide. For example, if it's a scheduler attribute, say who can set it or read it, and say what type it is.
When you're designing, consider performance, scalability, resilience, security, maintainability, usability, and upgrades. Work to make the interface consistent with the rest of PBS.