How to document CSS?

Asked

Viewed 214 times

4

I was documenting the typescript of my Angular project using Jsdoc basing myself in this question, and I was left with the following doubt.

How can I document my CSS classes and components of my Angular project (and other future projects), showing their possible behaviors, basic description and other relevant data? And there’s a documentation file generator, like the javadoc java?

Example of possible documentation:

/**
 * @description modifica comportamento da tag "header"
 * @screensize min 1080
 */
@media only screen and (min-width: 1080px){
    header{ /* aqui ocorre uma mudança de comportamento */ }
}

Remembering that I’m thinking about the behavior of documentation based on what I’ve seen in other languages, such as Javascript, PHP and Java.

css css3 documentation
  • 1

    I am not saying that it is not a great doubt, but I ask myself (and ask others) "why?" , I mean, since this would help something, I really can’t see where something visual other than "functions" could be documentable, up to about half a turn might make sense. What would be documentable in my view would be "css classes", but outside of the doc css and maybe outside the "context of it", I mean, would be the "Rules" CSS can be used in many ways, would complicate pointing out everything or am I mistaken?

  • Actually, that’s exactly why I asked. I don’t know if I’ll have any real gain or just get in the way, but the only way to know is to test (I think)

  • 1

    @Guilhermenascimento I see two ways to document, one would be the guide to good practices of use and writing methodologies. And the other guides the documentation of something closer to a design system

  • 1

    @hugocsl this as I said in my comment is to document the "classes" and not the CSS, the rest is style organization, which is not documenting, but is only implicit to facilitate the documenting and only.

  • 1

    @Arthursiqueira what Ugo commented and replied seems useful, but it only fits the classes, q was just what I said in the first comment ... but it is not documenting the CSS in fact.

  • 1

    I am voting to close because I believe the question is "too broad", not that it is the author’s fault, on the contrary, it is a "dark" subject, but in my previous comments I have already pointed out some things that may arise as problems, does not mean that the question is not interesting, only that the problem is that CSS can be used in many ways, each person works in a way with CSS (seriously there are many) and can come people with talk of "design" as WELL, but is not the focus, the question can be answered in many ways and none of them is in fact solution to any [...]

  • 1

    [...] if the question is edited and cites something more specific than you want to document, for example, documenting roles for the team, or documenting the pattern you should follow, or documenting based on comment markup and "Rules" (CSS) behavior, then I will vote to reopen (if it appears to have improved). I want you to understand that I am not doing evil or anything, I participate for a long time on the site and by experience of the "health" of the site/ community I am voting, and when all pointers are right I will give my support to reopen.

  • @Guilhermenascimento I understand his point, and so I corrected the question. Thank you for your cooperation, and I hope I’ve been clearer

  • Great, this point and the issue show how the answer that arose should not have been made so quickly, what you expressed in your question was precisely what I understood at the beginning, but it seems that it was different from what Hugo understood, some things are not a matter of giving "your contribution" (2 cents) but rather comment and try to extract better details from the author of the question before answering.

  • @Guilhermenascimento then I answered with what I thought appropriate, and as the question was edited I too edited my answer. We each collaborate the way we think best. I understood it a little differently even from you, so I followed a line that I thought would already be within the scope of the question.

  • 2

    @hugocsl don’t take this the wrong way, I’m not talking about your person or attitude directly, I’m talking about what I believe is healthy for the site and that this question has many interpretations, which would fit a number of possible closures before being actually answered, there is nothing to feel "attacked" (not that ;)

  • 1

    The biggest problem here is that in the same way that @hugocsl answered, we could have several others with no similarities, each one can invent a new way to respond. Other than that, the concept of documenting something is very broad (e.g. of the things that came to mind, none is in the answer given). It has a tool recommendation part that definitely does not fit in the scope. Besides, if a CSS gets complex to the point of needing documentation, it is a sign that the path is backwards, it would be better a tool to generate CSS based on a specification doc then.

Show 7 more comments

1 answer

3


There are ways to document the CSS, I see two ways to do this. The first would be to standardize the writing of the CSS within a team. Some companies already use this, including Google and Mozilla with their Style Guides.

Google Guide https://google.github.io/styleguide/htmlcssguide.html project on Github https://github.com/google/styleguide

Mozilla’s Guide https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS

inserir a descrição da imagem aqui Source: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Code_guidelines/CSS

The main intention of this documentation, guide, is to maintain the writing pattern within the team. Even the documentation can also signal if some methodology will be used with BEM or DRY, or if you’re going to use some preprocessor like SCSS or Stylus.

Another way of documenting is more focused on system design management like the Material Design and the very Bootstrap. In their project the intention is to facilitate the life of the developer, but mainly to maintain the standard of the code, because the source of all the team is only one. This can avoid the divergence and inconsistency of the CSS writing form within the project.

inserir a descrição da imagem aqui Source: https://material.io/develop/web/components/buttons/

Now about tools to document that itself GitHub is quite used for these things.

To document the design system you can use Zeroheight https://zeroheight.com/ or Outline https://www.getoutline.com/ (there are many others, just search on Google )

In development environment you can yes leave comments and other instructions. The largest Git project is Bootstrap, a virtually CSS-based framework and the source code there are a lot of comments and things like that. Already in the distribution files (dist) they are removed (probably by some packer used before moving the project up to production).

Here is an example taken from the GitHub of Bootstrap4

inserir a descrição da imagem aqui

OBS: As I said, these comments are on SCSS yet, and should not go into the final production environment, it only helps to maintain the code and makes it easier for those who join the team to understand what is happening in the code. It’s not a rule, but if it’s a team culture, it’s worth documenting. Mainly taking into account the retention of knowledge since in IT the turnover is high, besides helping others of the team to understand what is being done.

Source: https://github.com/twbs/bootstrap/blob/master/scss/mixins/_grid.scss

  • This falls into what I said, documenting the classes and not exactly CSS. It’s not that it’s not a good answer, maybe it’s exactly what the AP is looking for, but the starting question makes you think of "more than one thing"

  • @Guilhermenascimento is not just about class names, if you notice the first image of the answer it involves the way to write etc. You know that in some teams there are even "correct" forms to write a comment inside the code etc. I do not know if it was exactly what the AP is looking for, but the references may help to give some light

  • Being classes or style, yet it’s nothing about the "document" directly, documenting for use seems ok, but it involves HTML+CSS, documenting CSS for team evolution ai is "OTHER 500", and that’s not clear in the question. It is no use beating the foot that has solution, or because we know a "thing" that really is the definitive whole problem, many questions should mature a little before receiving an answer... I even agree that it’s an interesting question, but it doesn’t mean that it really should be answered yet, maybe it needed some maturity.

  • @Guilhermenascimento understand your point of view William, some points are still obscure even, I’m just there leaving my 2 cents

Browser other questions tagged css css3 documentation

You are not signed in. Login or sign up in order to post.