I challenged myself to test out an idea for a informational site on a technical thing, Electron, that tried to be as concise and plainly worded as I could get it. So here's Essential Electron, something I'll keep tweaking!
Technical documentation can be long, jargon-heavy and hard to know where to begin with. I think having detailed documentation is good in general, but I felt there was a place for something simpler and took you from top to bottom on the topic in one go.
I set out last week to try and see what this idea might look like, which resulted in Essential Electron. It was an interesting challenge because I had to think about everything I wrote: is this essential, is this a new word or concept worth learning or is it jargon that can be expanded? And cut, cut, cut. I tried to use these guidelines:
- Main section should be 2-3 sentences.
- New concepts/words defined.
- Jargon replaced with expanded phrasing.
- Graphic added when applicable.
- Links for more information provided in each section.
I wanted to take people through the flow of learning what Electron is, what development is like and how to get started, while remaining high-level. Someone should be able to go through each of the sections and only read the large text and still get a good sense of what Electron is. If a word or concept is new they can check the definitions. If a particular section is of interest they can use the resources to get more information.
I pulled and tweaked some graphics from a previous workshop I'd done to help illustrate this points. I'm pretty happy with the experiment though I have some more ideas and will keep refining this. Hope it turns out useful to some!
- Site: jlord.us/essential-electron
- Repository: gh/jlord/essential-electron