Update documentation process

[elseloop]

As @ajmueller notes in #108, our current documentation “is sub-optimal due to limitations of sassdoc.” We should explore some new options for generating and expanding our documentation.

Some considerations:

• It would be nice to remove the Ruby dependency entirely from Phoenix, preferably using a JS-based solution we can roll into our existing build system.
• We shouldn't give up any features in our existing documentation.
• We should be able to include documentation inline within our partials.
• Alongside generated styles, we should be able to include Sass and HTML for output in the documentation.

Some candidates:

• StyleDown: Node-based; looks for Markdown in .scss docs.
• StyleDocco: Node-based; allows Markdown in inline .scss documentation for generated examples
• Holograms: really nice and full-featured. Has a Ruby dependency, but does have a decent-looking Gulp plugin available on NPM (still requires Ruby, but we could at least set up a task for it in our existing setup). Uses YAML for inline docs.
• Others

[KittyGiraudel]

is sub-optimal due to limitations of sassdoc.

What are those limitations please @elseloop?

[ajmueller]

@HugoGiraudel in looking at newer versions of sassdoc, it looks like you guys have addressed the limitations (we originally wrote the documentation over a year ago and had simply been following the original paradigm since). We just haven't looked into a new documentation tool (or new version of sassdoc) for some time. Some of the original limitations were:

• documenting for functions and mixins only (we worked around this by utilizing categories and "function names" when appropriate)
• no ability to output samples in markup (which appears to have been resolved by allowing Markdown in descriptions?)
• a dependency on Ruby/no ability to incorporate into our Gulp build

What I loved about your system originally was JSON output, which allowed for us to parse it however we needed. With the theming capabilities now, I think sassdoc will fit the bill perfectly. I'll have to dig into it more, but it's looking very promising.

Thanks for checking in and if I see anything, I'll let you know!

[KittyGiraudel]

@ajmueller Actually I realized after posting my comment that you were using a completely different version of SassDoc. The one you used has nothing to do with today's SassDoc whatsoever. Not the same team (none of the four of us did work on the project you used), not the same language (I believe it was Ruby, we are using Node), not the same features (we provide much more features, honestly) and not the same goal (especially not the same way of doing).

We are about to release v2 of https://github.com/sassdoc/sassdoc. Docs can be found here: https://sassdoc.com/develop/.

Cheers.

[ajmueller]

Awesome, thanks! I saw the tweet about v2 yesterday and will definitely be checking it out.

[ajmueller]

@elseloop I've started a feature branch for this work: https://github.com/isitedesign/Phoenix/tree/feature/sassdoc-2. So far I've only removed the references to the old Sassdoc to give us a clean slate from which to start. Let me know if you'd like a hand in getting this started.

[ajmueller]

@elseloop have you had a chance to begin any implementation of Sassdoc 2? I'm having trouble getting it to recognize comments in files that aren't at the top of the css directory on a client project. Anything contained within functions, mixins, etc. is ignored. One thing I changed that I thought would fix it is the paths variable for the CSS driver. It was './css/*.scss' and I changed it to './css/**/*.scss' as seen on the Sassdoc site.

[KittyGiraudel]

If you truly have an issue with your set up, feel free to open an issue on the official repository so we can help you.

[ajmueller]

Thanks @HugoGiraudel. I have a feeling it might be how we structure our build scripts, so I'm going to test it more before I create an issue.

One question, though: does Sassdoc follow @import statements?

[KittyGiraudel]

One question, though: does Sassdoc follow @import statements?

Nope. SassDoc usually runs on a folder (with optional exclude patterns).

[ajmueller]

@HugoGiraudel the issue was due to me leaving in extra comments that I hadn't yet converted. For instance:

/// Description
/// @name test
// extra comment
@function test() ...

If any comment is left there directly above the Sass item, no matter the content (even just a string), the annotations are ignored and not parsed into the Sassdoc generated documentation. I can't think of an instance where this could be problematic since any comment you'd likely put there could (and should) be part of the description, but it could be seen by some as a bug since it means removing the ability to otherwise normally comment Sass code.

[KittyGiraudel]

This is the expected behaviour. To put it simply, a SassDoc compliant comment has to come directly before a valid item (function, mixin, placeholder or variable). If there is anything else than empty lines between them both, the comment is simply discarded.

[ajmueller]

That's what I thought, but just wanted to check. As I mentioned, this shouldn't really be an issue. Thanks @HugoGiraudel!

[ajmueller]

Still on the to-do list:

• document $options maps
• clean up/provide better examples
• proofread
• theme
• better categorization of "General" (or rename others to match casing)
• define access of some functions? Does anything other than the number-as-words function fit under private?

[ajmueller]

Following today's tech meeting, here are some points for discussion:

• Elimination of duplicate markup in PHP templates and CSS comments used for Styledown
• Using Jade/Twig/etc. as a method of doing all of our templating as a potential means of eliminating such duplication
• Scope of Style Guide vs. Pattern Library and the audiences for each

Overall it seems that we, as an agency, have bigger discussions around our deliverables and audiences that need to happen.

In addition, here are some examples to comb through of how various entities handle style guides:

http://styleguides.io/examples.html

[jbascue]

I think it makes sense to define our intended audiences (defined by roles) which in turn will help us form a more complete problem statement to work from and help us determine the appropriate deliverable for each.

As I see it, our audiences could generally fall into these categories and each have different needs:

• Everyone
  • Stakeholders, creative, UX, content entry, project management, development, literally everyone involved on the project
• Experience Design
  • front end development, creative, user experience, perhaps even content
• Development
  • Anyone involved in the implementation or development

Experience Design could perhaps be rolled into Everyone.

[kamsar]

Sounds like a job for a working group @stoff :)

[ajmueller]

:+1: @kamsar

Some reading that I think will help inform our decisions:

• https://medium.com/@operatino/living-style-guide-tools-in-depth-overview-28cfffb92d05
• http://alistapart.com/article/creating-style-guides
• http://24ways.org/2011/front-end-style-guides
• https://speakerdeck.com/hagenburger/style-guide-driven-development

(the last three are linked to in the first article)

[stoff]

Chris Coyier recently weighed in on Where Style Guides Fit Into Process. His conclusion? "There are no answers".

Perhaps the best approach is to have several possible workflows in pocket, and choose one that is a good fit for each project's unique mix of internal and client personalities.

[ajmueller]

For the next release, 1.3.0, we will be adding Sassdoc. Automatic Style Guide generation will be treated in a different release.