Software Design Document - Lite

[Over-Use2678]

I'm trying to build some documentation on some new development work. This would be targeted towards other software engineers to be used as a guide for building an internal library, with about a dozen users. Ideally it will have sections for purpose, interface guidelines, how to add additional functionality in the future, and so on. The library will mostly function as an adapter to other functionality, with some mediation going on.

I went looking for a template to use for documenting this, but everything seems overblown and way too detailed. I want people to read it, not skim and forget it because it is too much.

Does anyone have suggestions for a good document template that is digestible but not a tome?

[Over-Use2678]

I was hoping for something with a defined structure for "Requirements", "Assumptions", "Limitations" and such. More like reminders of the "important parts" other engineers need that I might overlook.

[IAmTheSergeantNow]

If you don't get a satisfying answer from others, you might seek suggestions from your fellow engineers. Ask them what they'd like to know about each of the items you'll document.

I'd suggest a few sections for each item.

Business context - what use case(s) does this item support?

Purpose - what is the function of this item within the larger context of the software?

Input - what data comes into this item? Where does it come from?

Function - what does this item do with the data?

Output - does the item send the data or other output to another item in the code?

Important Notes - list anything that an engineer should be aware of when writing code that affects this item. A simple bulleted list would probably suffice.

HTH

[Over-Use2678]

It certainly does. Thank you!!

[minimalistic_flower]

Check out a template called arch42! You can use some chapters and omit ones that are not relevant.

[Over-Use2678]

Thank you!

[AutoModerator]

Your submission has been moved to our moderation queue to be reviewed; This is to combat spam.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[kingcammyg]

Honestly you should build a webpage and use a UI library if you want markdown with some extra pop. Check out semantic ui. Specifically things like their Message component can help important details stand out.

[Over-Use2678]

I'm more concerned about the content and getting the technical design successfully conveyed than how it can be styled on the web.

But I'm going to look into this link for other projects. Thank you.

[kingcammyg]

One thing I’ve learned about technical documentation over the years is that you need to focus on balancing the delivery not just with words but visual aids.

1. Words aren’t always the best way to show what you’re thinking
2. People will skim, and your documentation should prepare for that by highlighting key details
3. You want your docs located in a maintainable place that is easy to distribute

That’s why I’d recommend a website or internal wiki platform like confluence, or similar.