Help getting started with MDN and other questions

MDN
#1

Hello. I am doing a documentation review for my university’s module and just got started. It seems that here is a lot going on, so I would like to ask for some help. I would like to post questions in here that I come up with during my work, so I would be glad if you could help me on my way.
At first, I have tried to join IRC, but something is not working, as no version of ChatZilla is compatible with my Firefox. Thus, I came here for help.
Finally, if I this topic is not suitable on this forum, can you please redirect me to the appropriate location, where I could ask questions in regards of contributing to Mozilla documentation. Thank you.

I already have one question. For example, the writing style guide states that “Phrases and sentences in bulleted lists should include standard punctuation. Periods must appear at the end of each sentence in a bulleted list, including the item’s final sentence, just as would be expected in a paragraph”. However, nothing is mentioned about single words in bulleted lists, or mixed bulleted lists, which can include words and sentences. For example, which option would be correct here.
This one?
This can cause following symptoms:

  • Headache
  • Fever
  • Skin rash or dermatitis
  • Dry mouth

Or this one?
This can cause following symptoms:

  • Headache.
  • Fever.
  • Skin rash or dermatitis.
  • Dry mouth.

Thank you.

Feedback for MDN web doc revisions
#2

Hi Igor
I suggest you use Stack Overflow for general questions. For example you could search How to + IRC or IRC+ get started

#3

Hi @Igor-Sangin! Welcome to the MDN community, and thanks for your interest in contributing! I am happy to help with MDN-related questions on this forum; feel free to @mention me so I get emailed a notification.

IRC and Mozilla is a bit difficult right now; we are in the process of moving off IRC for various reasons, but the new public alternative hasn’t been announced yet.

And as for your documentation question — this is a good point; we don’t mention what to do in the case of single word or mixed bulleted lists.

I would advise the first option being preferred in such cases. This is what I always do, and I think it just looks and feels better. Feel free to update our guideline docs to state this, if you like :wink:

And also feel free to ask me for a review on docs that you update.

All the best.

1 Like
#4

Thanks for the replies.

@chrisdavidmills
I just have updated one document, you can find it here
https://wiki.developer.mozilla.org/en-US/docs/Web/Accessibility/Cognitive_accessibility

Maybe I shouldn’t have started with such a big document, but I had noticed a lot of mistakes in there and so I thought that this will be good practice for me. I think this document still in need of editing and I might come back to it soon. Meanwhile, can you please review my work and give me some feedback? I would be grateful.

I have definitely missed something and I am already not sure if I should change the bulleted list, where each line ends with semicolons. The writing style guide does not mention it in this context, however, some other online sources state that this is not incorrect and can be used. On the other hand, I thought that for consistency reason, this list should be changed? However, I decided to leave it as it is for the moment.

Thank you.

#5

Thanks @Igor-Sangin, you’ve done a great job on that article — this is much improved.

I’d be happy for you to change the semi colon list to recommended practice.

Note that you’ll probably come across a lot of places on MDN where the text style doesn’t follow the guidelines. They are more loose recommendations really — with thousands of pages, and hundreds of contributors, enforcing them would be like trying to boil the ocean. But we always do what we can, and I think your changes have met a nice balance of improving style consistency and fixing out and out errors.

#6

As for punctuation in lists, the general rule I follow is this:

  • If a bullet point is a complete sentence, use proper sentence punctuation.
  • If a bullet point is what I think of as a “nearly complete sentence”, use sentence punctuation. These are items which are long enough and have enough complexity of structure that you might mistake it as a sentence at first reading, such as “A value which represents the state of the wildfire as of the given time of day.” It’s not a complete sentence, but it’s long enough and has all the parts of speech in there, but it’s not structurally a complete sentence.
  • The items in a list should be consistent in this regard (if one is a complete sentence, they should all be either complete sentences or “nearly complete sentences”).
  • If a bullet point is just one word, definitely no period (unless the other entries have them).

Those are the rules I generally follow, and have done so since I started on MDN 13.5 years ago. :slight_smile:

Sheppy

1 Like
#7

Thank you @sheppy

I have translated these two documents into Russian now:


and

@chrisdavidmills and @sheppy, I believe you are not Russians, so you won’t be able to review them, right? Is there a way or is there a person whom I might ask about my translations?
Also, in the Algorithm original document, I found several mistakes, although that page didn’t have a tab which stated that review is required, and I fixed them. One thing I am not sure about - I have changed all instances of the word “Algorithm” from uppercase to lowercase because it seems right in this context. Please correct me if I’m wrong.
Thank you.

1 Like
#8

@Igor-Sangin thank you for your continued work!

I believe you are not Russians, so you won’t be able to review them, right? Is there a way or is there a person whom I might ask about my translations?

That is correct. And we don’t have any staff members who we could ask about this. For most localization work, we rely totally on volunteers, as we don’t have the facility to do it ourselves. This is not very good, so at some point in the future we are aiming to staff localization projects appropriately. But this is a long way off.

Also, in the Algorithm original document, I found several mistakes, although that page didn’t have a tab which stated that review is required, and I fixed them. One thing I am not sure about - I have changed all instances of the word “Algorithm” from uppercase to lowercase because it seems right in this context.

This sounds reasonable to me. Note that we don’t constently get even all the English documentation reviewed reliably all the time, so mistakes do sometimes creep through. We have too much documentation and too few staff to guarantee it, although we do make sure that high priority items are reviewed.

#9

@chrisdavidmills, thank you for giving me permission to create new pages! I have added two entries to the glossary, which you can find here: Botstrap and Favicon. Sorry, I haven’t done the Agile, because it might be more time consuming and also as these my first pages, not sure if I made too many mistakes or not, in regards to styling and other rules.
Can you please check these two entries and let me know what I have missed and what do I need to fix? Also, I cannot actually see these terms on glossary main page. Does it require approval or something else?

#10

Thanks @Igor-Sangin, these look really good! I’ve given them a copy edit and rounded out the information they contain, plus I’ve added some tags.

#11

And the page links are now appearing on the main glossary page — sometimes the static page does not regenerate immediately, but this can usually be remedied by doing a “Shift Refresh” (Ctrl/Cmd + Shift + R) to force it to regenerate.