Hacker News new | past | comments | ask | show | jobs | submit login

Nothing wrong with writing your own SSG (I recently rolled my own solution for my blog as well), but the most important part of the new solution is glossed over by the author: documentation. What's critical, regardless of the solution you use, is to get a runbook of your software.

By way of example, my hand-rolled blog has a README file which lists these things in it. Whenever you pick up a new SSG or create your own you should make sure that you have a good plan for at least these things:

1. How to start writing a new post. For me, that's the script to fill out the template, plus the instructions to run the dev server.

2. Frontmatter fields supported. If there's too many to list all of them, at least list every one you've used before, since you'll probably use those again.

3. Tools for writing. For me, that's a few scripts to do things like properly import media.

4. Publishing. This is a full checklist including "verify mobile", "verify excerpt on posts page", "run publish/deploy", "submit to these sites".

One of the reasons your personal SSG feels better than anything is because you know every nook and cranny in it. That feeling will go away after about 6 months, and you'll thank yourself for having written good documentation.




Agreed. Additionally, this should go for every piece of software you write for yourself, not just your SSG.


I've never heard the term "runbook" before, but it sounds very useful. Thanks!

https://en.wikipedia.org/wiki/Runbook




Consider applying for YC's Spring batch! Applications are open till Feb 11.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: